home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
IRIX Base Documentation 1998 November
/
IRIX 6.5.2 Base Documentation November 1998.img
/
usr
/
share
/
catman
/
p_man
/
cat3
/
libpod.z
/
libpod
Wrap
Text File
|
1998-10-30
|
10KB
|
199 lines
LLLLIIIIBBBBPPPPOOOODDDD((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo LLLLIIIIBBBBPPPPOOOODDDD((((3333))))
LLLLIIIIBBBBRRRRAAAARRRRYYYY DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
_l_i_b_p_o_d provides a C language application programming interface (API) to
the Printer Object Database (POD). The _l_i_b_p_o_d library provides printer
driver developers with an API to create and maintain a POD and provides
application developers with the means to acquire detailed information
about a printer. A POD contains information on the current configuration,
state and job history of a single printer. Each printer physically
installed on a system maintains its own POD. All interaction with a
printer's POD should be done through _l_i_b_p_o_d. Direct modification of the
POD files is strongly discouraged. For detailed information on the
creation and format of the POD files refer to the _p_o_d(_4) man page.
PPPPOOOODDDD FFFFIIIILLLLEEEESSSS
A Printer Object Database consists of three separate ASCII text files.
The name of each POD file is formed from the printer name and the suffix
._c_o_n_f_i_g, ._s_t_a_t_u_s and ._l_o_g, respectively. The information contained in
each file is summarized below.
[[[[pppprrrriiiinnnntttteeeerrrr nnnnaaaammmmeeee]]]]....ccccoooonnnnffffiiiigggg
This file contains detailed information on the printer's
capabilities. Examples include the possible paper sizes,
printer location and available fonts. Initially, this file
is created by the printer driver developer and a copy is
installed when the printer is added to the system. The
contents of this file are typically maintained by the
system administrator and are not normally changed.
[[[[pppprrrriiiinnnntttteeeerrrr nnnnaaaammmmeeee]]]]....ssssttttaaaattttuuuussss
This file contains information about the current
operational status of the printer. The information in the
file indicates whether the printer is busy, what type of
printing media is installed, and so on. The contents of
this file change during every print job.
[[[[pppprrrriiiinnnntttteeeerrrr nnnnaaaammmmeeee]]]]....lllloooogggg
This file contains the print job history for the printer,
information for old as well as current print jobs.
The default location for POD files is /_v_a_r/_s_p_o_o_l/_l_p/_p_o_d. The global
variable _P_D_p_o_d__p_a_t_h indicates the location of the POD files and is set to
the default path by _l_i_b_p_o_d. Note that _P_D_p_o_d__p_a_t_h is set to
/_u_s_r/_s_p_o_o_l/_l_p/_p_o_d which is linked to /_v_a_r/_s_p_o_o_l/_l_p/_p_o_d. This is for
compatilibty with printer hosts running older versions of the IRIX
operating system. If POD files are to be located in a directory other
than the default, _P_D_p_o_d__p_a_t_h should be set to the pathname of the new
location. _P_D_p_o_d__p_a_t_h is declared in the header file _p_o_d._h. Note that the
maximum string length for _P_D_p_o_d__p_a_t_h is PPPPDDDD____SSSSTTTTRRRR____MMMMAAAAXXXX. This includes the
terminating NULL character.
PPPPaaaaggggeeee 1111
LLLLIIIIBBBBPPPPOOOODDDD((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo LLLLIIIIBBBBPPPPOOOODDDD((((3333))))
FUNCTIONS
Many _l_i_b_p_o_d functions come in two forms, a standard form and a local
form. The POD files reside only on the system to which the printer is
physically connected, referred to as the printer host. Therefore, to
provide information about a printer located on another system, _l_i_b_p_o_d
must be able to communicate across the network. The standard form of the
_l_i_b_p_o_d functions (i.e. functions whose names do not contain the word
"local") automatically determine whether the specified printer is located
on the user's system (a local printer), or whether the printer is on a
remote system (a remote printer). After determining where the printer is
located, the standard functions access the POD files on the appropriate
system. Since network communication carries a certain amount of
performance overhead, _l_i_b_p_o_d provides the local functions (i.e. the names
with the word "local"). These functions are provided for use by programs
that are guaranteed to be run on the printer host machine. A printer
driver is an example of such a program. Typically, user application
programs such as printer status tools use the standard form of the _l_i_b_p_o_d
functions, since it is likely that these programs will need to work with
remote printers.
Note that the functions that write to POD files (e.g. _P_D_L_o_c_a_l_W_r_i_t_e_L_o_g)
are available only in local form. Since only printer drivers should have
a need to write to the POD files, there is no need to provide for writing
to the files from anywhere except from the system to which the printer is
physically connected.
DDDDeeeettttaaaaiiiilllleeeedddd IIIInnnnffffoooorrrrmmmmaaaattttiiiioooonnnn MMMMaaaannnniiiippppuuuullllaaaattttiiiioooonnnn
PDReadInfo PDLocalReadInfo
PDLocalWriteInfo
SSSSttttaaaattttuuuussss FFFFiiiilllleeee MMMMaaaannnniiiippppuuuullllaaaattttiiiioooonnnn
PDReadStatus PDLocalReadStatus
PDLocalWriteStatus
PDReadOpStatus PDLocalReadOpStatus
LLLLoooogggg FFFFiiiilllleeee MMMMaaaannnniiiippppuuuullllaaaattttiiiioooonnnn
PDReadLog PDLocalReadLog
PDLocalWriteLog
CCCCoooonnnnvvvveeeennnniiiieeeennnncccceeee FFFFuuuunnnnccccttttiiiioooonnnnssss
PDMakeMessage
PDFindPageSize
PDGetCurrentResolution
PDGetSizeCodeByName
PDGetNameBySizeCode
EEEExxxxeeeeccccuuuuttttiiiioooonnnn EEEErrrrrrrroooorrrr HHHHaaaannnnddddlllliiiinnnngggg
PDPerror
PPPPaaaaggggeeee 2222
LLLLIIIIBBBBPPPPOOOODDDD((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo LLLLIIIIBBBBPPPPOOOODDDD((((3333))))
LIBRARY ACCESS
Programs that call _l_i_b_p_o_d functions must include the _p_o_d._h header file
located in the /_u_s_r/_i_n_c_l_u_d_e directory. In addition, the programs must
link with the _l_i_b_p_o_d._a library located in /_u_s_r/_l_i_b. Programs that use the
standard functions must also link with _l_i_b_s_p_o_o_l._a. Programs that use only
the local functions need not link with this additional library. The link
lines for each case would be:
When using standard functions: ... -lpod -lspool ...
When using only local functions: ... -lpod ...
NNNNEEEETTTTWWWWOOOORRRRKKKK CCCCOOOOMMMMMMMMUUUUNNNNIIIICCCCAAAATTTTIIIIOOOONNNN
To provide remote printer POD information, _l_i_b_p_o_d communicates over the
network with the _p_o_d_d(_1_M) daemon on the remote machine. Since the network
or remote machine may be down when a _l_i_b_p_o_d function is executed, a
timeout may occur and the function will return the appropriate error
code. The timeout period can be specified by setting the global variable
PPPPDDDDnnnneeeetttt____ttttiiiimmmmeeeeoooouuuutttt to a value in seconds. The default timeout period is shown
in the header file _p_o_d._h. While a large timeout period is appropriate
when reading printer status, a much smaller timeout may be appropriate
for browsing printer configurations.
For more information on the daemon refer to the _p_o_d_d(_1_M) man page.
DDDDEEEEBBBBUUUUGGGGGGGGIIIINNNNGGGG
If the global variable _P_D_d_e_b_u_g is set to a non-zero value, _l_i_b_p_o_d will
print debugging information to standard error during execution. _P_D_d_e_b_u_g
is declared in the header file _p_o_d._h.
WWWWAAAARRRRNNNNIIIINNNNGGGG
The standard form of the _l_i_b_p_o_d functions call the _l_i_b_s_p_o_o_l function
_S_L_G_e_t_P_r_i_n_t_e_r_I_n_f_o. This _l_i_b_s_p_o_o_l function is not reentrant. This means
that any pointer returned by a previous call to _S_L_G_e_t_P_r_i_n_t_e_r_I_n_f_o will be
invalid after a call to the standard form of the _l_i_b_p_o_d functions.
SSSSEEEEEEEE AAAALLLLSSSSOOOO
pod(4), libspool(3), podd(1M)
PPPPaaaaggggeeee 3333